/* libfake437 - a library for the rendering of code page 437 `graphics'
 * Copyright (C) 2008, 2009, 2010, 2011 Jack Kelly <endgame.dos@gmail.com>
 *
 * This library is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation, either version 3 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 ** @node F437Surface Operations
 ** @chapter F437Surface Operations
 **
 ** A @code{F437Surface} wraps a @code{SDL_Surface*}, and is passed as
 ** an argument to all drawing calls.
 **/

#ifndef FAKE437_SURFACE_H
#define FAKE437_SURFACE_H

#ifdef __cplusplus
extern "C"{
#endif

/**
 ** @deftypefun F437Surface* f437_surface_new @
 **   (SDL_Surface*    @var{surface},         @
 **    const F437Font* @var{font},            @
 **    int             @var{scale})
 **
 ** Creates a @code{F437Surface} that is centred within @var{surface}
 ** and is as wide and as tall as possible while still able to fit
 ** within @var{surface}. It should be freed with
 ** @code{f437_surface_free} when no longer needed. An
 ** @code{F437Surface} assumes no ownership of any pointers it comes
 ** in contact with, and @var{surface} and @var{font} must have a
 ** longer lifespan than the returned @code{F437Surface*}.
 **
 ** A surface has a foreground and background colour, which are used
 ** when printing. These are initially set to @code{NULL}
 ** (transparent). The surface also has an insertion point, which
 ** starts at the top-left corner.
 **
 ** @var{scale} is an integer multiplier for the font: an 8*14 font
 ** with scale 2 will draw 16*28 glyphs.
 **
 ** This function calls @code{abort} if there is an allocation
 ** failure.
 **
 ** @end deftypefun
 **/
F437Surface* f437_surface_new(SDL_Surface* surface,
                              const F437Font* font,
                              int scale);

/**
 ** @deftypefun F437Surface* f437_surface_try_new @
 **   (SDL_Surface*    @var{surface},             @
 **    const F437Font* @var{font},                @
 **    int             @var{scale})
 **
 ** As @code{f437_surface_new}, but returns @code{NULL} instead of
 ** aborting on allocation failure.
 **
 ** @end deftypefun
 **/
F437Surface* f437_surface_try_new(SDL_Surface* surface,
                                  const F437Font* font,
                                  int scale);

/**
 ** @deftypefun F437Surface* f437_surface_new_sized @
 **   (SDL_Surface*    @var{surface},               @
 **    const F437Font* @var{font},                  @
 **    int             @var{width},                 @
 **    int             @var{height})
 **
 ** Create a surface of specified width and height. The surface is
 ** scaled as large as possible and centred. Return @code{NULL} if
 ** @var{surface} is too small for the requested size, or on
 ** allocation failure.
 **
 ** @end deftypefun
 **/
F437Surface* f437_surface_new_sized(SDL_Surface* surface,
                                    const F437Font* font,
                                    int width,
                                    int height);

/**
 ** @deftypefun SDL_Surface* f437_surface_free @
 **   (F437Surface* @var{surface})
 **
 ** Frees a @code{F437Surface}, but not the @code{SDL_Surface} or
 ** @code{F437Font} it was pointing to. Returns a pointer to the
 ** @code{SDL_Surface} used to make the @code{F437Surface}.
 **
 ** @end deftypefun
 **/
SDL_Surface* f437_surface_free(F437Surface* surface);

/**
 ** @deftypefun void f437_surface_putc @
 **   (F437Surface* @var{surface},     @
 **    int          @var{ch})
 **
 ** @deftypefunx void f437_surface_puts @
 **   (F437Surface* @var{surface},      @
 **    const char*  @var{str})
 **
 ** Write a character or string to the surface. Because code page 437
 ** defines various dingbats for the low characters, characters like
 ** @code{'\n'} will not behave as they would when writing to a
 ** terminal.
 **
 ** Printing automatically wraps left-to-right, top-to-bottom, and
 ** will wrap around the whole screen.
 **
 ** @end deftypefun
 **/

void f437_surface_putc(F437Surface* surface, int ch);
void f437_surface_puts(F437Surface* surface, const char* str);

/**
 ** @deftypefun void f437_surface_fg   @
 **   (F437Surface*     @var{surface}, @
 **    const SDL_Color* @var{fg})
 **
 ** @deftypefunx void f437_surface_bg  @
 **   (F437Surface*     @var{surface}, @
 **    const SDL_Color* @var{bg})
 **
 ** Change the foreground/background colour of characters printed to
 ** the surface.
 **
 ** @end deftypefun
 **/
void f437_surface_fg(F437Surface* surface, const SDL_Color* fg);
void f437_surface_bg(F437Surface* surface, const SDL_Color* bg);

/**
 ** @deftypefun void f437_surface_goto_xy @
 **   (F437Surface* @var{surface},        @
 **    int          @var{x},              @
 **    int          @var{y})
 **
 ** Move the insertion point of the surface.
 **
 ** @end deftypefun
 **/
void f437_surface_goto_xy(F437Surface* surface, int x, int y);

#ifdef __cplusplus
}
#endif

#endif
